---
title: observe()
description: 'Complete API reference for the observe() method'
icon: 'magnifying-glass'
---

<CardGroup cols={1}>
<Card title="Observe" icon="magnifying-glass" href="/v2/basics/observe">
  See how to use observe() to discover actionable elements and analyze web page structure
</Card>
</CardGroup>

### Method Signatures

<Tabs>
<Tab title="TypeScript">

```typescript
// With ObserveOptions
await page.observe(options: ObserveOptions): Promise<ObserveResult[]>

// String instruction shorthand
await page.observe(instruction: string): Promise<ObserveResult[]>
```

**ObserveOptions Interface:**
```typescript
interface ObserveOptions {
  instruction?: string;
  modelName?: AvailableModel;
  modelClientOptions?: ClientOptions;
  domSettleTimeoutMs?: number;
  drawOverlay?: boolean;
  iframes?: boolean;
}
```

</Tab>
<Tab title="Python">

```python
# With parameters
await page.observe(
    instruction: str,
    dom_settle_timeout_ms: int = None,
    iframes: bool = None,
    model_name: AvailableModel = None,
    model_client_options: Dict = None
) -> List[ObserveResult]
```

</Tab>
</Tabs>

### Parameters

<ParamField path="instruction" type="string" optional>
  Natural language description of elements or actions to discover.
</ParamField>

<ParamField path="modelName" type="AvailableModel" optional>
  Override the default LLM model for this observation.
</ParamField>

<ParamField path="modelClientOptions" type="ClientOptions" optional>
  Model-specific configuration options.
</ParamField>

<ParamField path="domSettleTimeoutMs" type="number" optional>
  Maximum time to wait for DOM to stabilize before analysis.
  
  **Default:** `30000`
</ParamField>

<ParamField path="drawOverlay" type="boolean" optional>
  Whether to draw visual overlays on discovered elements (debugging).
  
  **Default:** `false`
</ParamField>

<ParamField path="iframes" type="boolean" optional>
  Set to `true` to search within iframes.
  
  **Default:** `false`
</ParamField>

### Response

**Returns:** `Promise<ObserveResult[]>`

Array of discovered actionable elements, ordered by relevance.

**ObserveResult Interface:**
```typescript
interface ObserveResult {
  selector: string;        // XPath selector to locate element
  description: string;     // Human-readable description
  method?: string;         // Suggested action method
  arguments?: string[];    // Additional action parameters
}
```

<ParamField path="selector" type="string">
  XPath selector that precisely locates the element.
</ParamField>

<ParamField path="description" type="string">
  Human-readable description of the element and its purpose.
</ParamField>

<ParamField path="method" type="string" optional>
  Suggested interaction method: `"click"`, `"fill"`, `"selectOptionFromDropdown"`, `"nextChunk"`, `"scrollTo"`, `"prevChunk"`.
</ParamField>

<ParamField path="arguments" type="string[]" optional>
  Additional parameters for the suggested action.
</ParamField>


### Code Examples

<CodeGroup>
```typescript TypeScript
// Basic element discovery
const buttons = await page.observe("find all clickable buttons");
const formFields = await page.observe("locate form input fields");

// Advanced configuration
const elements = await page.observe({
  instruction: "find important call-to-action buttons",
  modelName: "gpt-4.1-mini",
  domSettleTimeoutMs: 45000,
  drawOverlay: true
});

// Working with results
const [loginButton] = await page.observe("find the login button");
if (loginButton) {
  console.log("Found:", loginButton.description);
  console.log("Selector:", loginButton.selector);
  await page.act(loginButton); // Execute the action
}

// Filter results
const submitButtons = await page.observe("find all submit buttons");
const primarySubmit = submitButtons.find(btn => 
  btn.description.toLowerCase().includes('primary')
);

// Iframe search
const iframeElements = await page.observe({
  instruction: "find form fields inside the iframe",
  iframes: true
});
```

```python Python
# Basic element discovery
buttons = await page.observe("find all clickable buttons")
form_fields = await page.observe("locate the form fields")

# Advanced configuration  
elements = await page.observe(
    instruction="find important call-to-action buttons",
    model_name="gpt-4.1-mini",
    dom_settle_timeout_ms=45000
)

# Working with results
login_buttons = await page.observe("find the login button")
if login_buttons:
    button = login_buttons[0]
    print("Found:", button.description)
    print("Selector:", button.selector)
    await page.act(button)  # Execute the action

# Filter results
submit_buttons = await page.observe("find all submit buttons")
primary_submit = next((
    btn for btn in submit_buttons 
    if 'primary' in btn.description.lower()
), None)

# Iframe search
iframe_elements = await page.observe(
    instruction="find the form fields inside the iframe",
    iframes=True
)
```
</CodeGroup>

### Integration Patterns

<CodeGroup>
```typescript TypeScript
// Observe → Act workflow
const actions = await page.observe("find checkout elements");
for (const action of actions) {
  await page.act(action);
  await page.waitForTimeout(1000);
}

// Observe → Extract workflow
const tables = await page.observe("find data tables");
if (tables.length > 0) {
  const data = await page.extract({
    instruction: "extract the table data",
    selector: tables[0].selector,
    schema: DataSchema
  });
}

// Element validation
const requiredElements = await page.observe("find the login form");
if (requiredElements.length === 0) {
  throw new Error("Login form not found");
}
```

```python Python
# Observe → Act workflow  
actions = await page.observe("find checkout elements")
for action in actions:
    await page.act(action)
    await page.wait_for_timeout(1000)

# Observe → Extract workflow
tables = await page.observe("find data tables")
if tables:
    data = await page.extract(
        instruction="extract the table data",
        selector=tables[0].selector,
        schema=DataSchema
    )

# Element validation
required_elements = await page.observe("find login form")
if not required_elements:
    raise Exception("Login form not found")
```
</CodeGroup>